---
title: Segmented Control
description: Using the Segmented Control in your project.
package: "@zag-js/radio-group"
---

A Segmented control allows users to make a single selection from multiple
exclusive options, providing a visually distinct and intuitive way of
interacting with radio inputs.

<Resources pkg="@zag-js/radio-group" />

<Showcase id="SegmentedControl" />

**Features**

- Syncs with `disabled` state of fieldset
- Syncs with form `reset` events
- Can programmatically set segmented control value
- Can programmatically focus and blur segmented control items

## Installation

To use segmented control add the radio machine to your project, run the
following command in your command line:

<CodeSnippet id="segmented-control/installation.mdx" />

## Anatomy

To set up the segmented control correctly, you'll need to understand its anatomy
and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="segmented-control" />

## Usage

First, import the radio group package into your project

```jsx
import * as radio from "@zag-js/radio-group"
```

The radio package exports two key functions:

- `machine` — The state machine logic for the radio widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

> You'll also need to provide a unique `id` to the `useMachine` hook. This is
> used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
radio machine in your project 🔥

<CodeSnippet id="segmented-control/usage.mdx" />

### Disabling the segmented control

To make a segmented control disabled, set the context's `disabled` property to
true

```jsx {2}
const service = useMachine(radio.machine, {
  disabled: true,
})
```

### Making the segmented control readonly

To make a segmented control readonly, set the context's `readOnly` property to
true

```jsx {2}
const service = useMachine(radio.machine, {
  readOnly: true,
})
```

### Setting the initial value

Use the `defaultValue` property to set the segmented control's initial value.

```jsx {2}
const service = useMachine(radio.machine, {
  defaultValue: "apple",
})
```

### Listening for changes

When the segmented control value changes, the `onValueChange` callback is
invoked.

```jsx {2-7}
const service = useMachine(radio.machine, {
  onValueChange(details) {
    // details => { value: string }
    console.log("segmented control value is:", details.value)
  },
})
```

### Usage within forms

To use segmented control within forms, use the exposed `inputProps` from the
`connect` function and ensure you pass `name` value to the machine's context. It
will render a hidden input and ensure the value changes get propagated to the
form correctly.

```jsx {2}
const service = useMachine(radio.machine, {
  name: "fruits",
})
```

## Styling guide

Earlier, we mentioned that each segmented control part has a `data-part`
attribute added to them to select and style them in the DOM.

### Indicator

Style the segmented control Indicator through the `indicator` part.

```css
[data-part="indicator"] {
  /* styles for indicator */
}
```

### Focused State

When the radio input is focused, the `data-focus` attribute is added to the root
and label parts.

```css
[data-part="radio"][data-focus] {
  /* styles for radio focus state */
}

[data-part="radio-label"][data-focus] {
  /* styles for radio label focus state */
}
```

### Disabled State

When the radio is disabled, the `data-disabled` attribute is added to the root
and label parts.

```css
[data-part="radio"][data-disabled] {
  /* styles for radio disabled state */
}

[data-part="radio-label"][data-disabled] {
  /* styles for radio label disabled state */
}
```

### Invalid State

When the radio is invalid, the `data-invalid` attribute is added to the root and
label parts.

```css
[data-part="radio"][data-invalid] {
  /* styles for radio invalid state */
}

[data-part="radio-label"][data-invalid] {
  /* styles for radio label invalid state */
}
```

## Methods and Properties

### Machine Context

The radio group machine exposes the following context properties:

<ContextTable name="radio-group" />

### Machine API

The radio group `api` exposes the following methods:

<ApiTable name="radio-group" />

### Data Attributes

<DataAttrTable name="radio-group" />
